<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.17">
<title>i3blocks</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment the following line when using as a custom stylesheet */
/* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
html{font-family:sans-serif;-webkit-text-size-adjust:100%}
a{background:none}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
b,strong{font-weight:bold}
abbr{font-size:.9em}
abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
dfn{font-style:italic}
hr{height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
audio,video{display:inline-block}
audio:not([controls]){display:none;height:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type=checkbox],input[type=radio]{padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,::before,::after{box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:0}
p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
table thead,table tfoot{background:#f7f8f7}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt{background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
:not(pre).nobreak{word-wrap:normal}
:not(pre).nowrap{white-space:nowrap}
:not(pre).pre-wrap{white-space:pre-wrap}
:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
pre>code{display:block}
pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
details{margin-left:1.25rem}
details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
details>summary::-webkit-details-marker{display:none}
details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
.listingblock>.content{position:relative}
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.prettyprint{background:#f7f7f8}
pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
pre.prettyprint li code[data-lang]::before{opacity:1}
pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
table.linenotable td.code{padding-left:.75em}
table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
pre.pygments span.linenos{display:inline-block;margin-right:.75em}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
td.tableblock>.content>:last-child{margin-bottom:-1.25em}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>*>tr>*{border-width:1px}
table.grid-cols>*>tr>*{border-width:0 1px}
table.grid-rows>*>tr>*{border-width:1px 0}
table.frame-all{border-width:1px}
table.frame-ends{border-width:1px 0}
table.frame-sides{border-width:0 1px}
table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
li>p:empty:only-child::before{content:"";display:inline-block}
ul.checklist>li>p:first-child{margin-left:-1em}
ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
td.hdlist2{word-wrap:anywhere}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background:#00fafa}
.black{color:#000}
.black-background{background:#000}
.blue{color:#0000bf}
.blue-background{background:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background:#fa00fa}
.gray{color:#606060}
.gray-background{background:#7d7d7d}
.green{color:#006000}
.green-background{background:#007d00}
.lime{color:#00bf00}
.lime-background{background:#00fa00}
.maroon{color:#600000}
.maroon-background{background:#7d0000}
.navy{color:#000060}
.navy-background{background:#00007d}
.olive{color:#606000}
.olive-background{background:#7d7d00}
.purple{color:#600060}
.purple-background{background:#7d007d}
.red{color:#bf0000}
.red-background{background:#fa0000}
.silver{color:#909090}
.silver-background{background:#bcbcbc}
.teal{color:#006060}
.teal-background{background:#007d7d}
.white{color:#bfbfbf}
.white-background{background:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,span.alt,summary{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]{border-bottom:1px dotted}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#header,#content,#footnotes,#footer{max-width:none}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>i3blocks</h1>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_example">Example</a></li>
<li><a href="#_installation">Installation</a></li>
<li><a href="#_getting_started">Getting started</a></li>
<li><a href="#_blocks">Blocks</a></li>
<li><a href="#_i3bar_properties">i3bar properties</a></li>
<li><a href="#_i3blocks_properties">i3blocks properties</a>
<ul class="sectlevel2">
<li><a href="#_command">command</a></li>
<li><a href="#_interval">interval</a></li>
<li><a href="#_signal">signal</a></li>
<li><a href="#_format">format</a></li>
</ul>
</li>
<li><a href="#_click">Click</a></li>
<li><a href="#_faq">FAQ</a></li>
<li><a href="#_debugging">Debugging</a></li>
<li><a href="#_license">License</a></li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>The hacker-friendly <code>status_command</code> for Sway and i3</p>
</div>
<div class="paragraph">
<p>i3blocks is a feed generator for text based status bars.
It executes your command lines and generates a status line from their output.
Commands are scheduled at configured time intervals, upon signal reception or on clicks.</p>
</div>
<div class="paragraph">
<p>The generated line is meant to be displayed by the <a href="https://i3wm.org">i3</a> window manager through its i3bar component, as an alternative to i3status.
This program naturally works out of the box with the <a href="https://swaywm.org">sway</a> Wayland compositor since it is a drop-in replacement for i3.</p>
</div>
<div class="paragraph">
<p>i3blocks is meant to be highly flexible but intuitive.
No library package is required, just output what your status bar expects, from your favorite programming language and your preferred format.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_example">Example</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[click]
full_text=Click me!
command=echo "Got clicked with button $button"
color=#F79494

# Guess the weather hourly
[weather]
command=curl -Ss 'https://wttr.in?0&amp;T&amp;Q' | cut -c 16- | head -2 | xargs echo
interval=3600
color=#A4C2F4

# Query my default IP address only on startup
[ip]
command=hostname -i | awk '{ print "IP:" $1 }'
interval=once
color=#91E78B

# Update time every 5 seconds
[time]
command=date +%T
interval=5</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_installation">Installation</h2>
<div class="sectionbody">
<div class="paragraph">
<p>i3blocks is already packaged for:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Archlinux: <a href="https://www.archlinux.org/packages/community/x86_64/i3blocks">i3blocks</a> in the community repository and <a href="https://aur.archlinux.org/packages/i3blocks-git">i3blocks-git</a> in the AUR</p>
</li>
<li>
<p>Gentoo: <a href="https://packages.gentoo.org/packages/x11-misc/i3blocks">x11-misc/i3blocks</a></p>
</li>
<li>
<p>Debian: <a href="https://packages.debian.org/i3blocks">i3blocks</a></p>
</li>
<li>
<p>Ubuntu: <a href="http://packages.ubuntu.com/i3blocks">i3blocks</a></p>
</li>
<li>
<p>Fedora (COPR): <a href="https://copr.fedorainfracloud.org/coprs/wyvie/i3blocks">i3blocks</a></p>
</li>
<li>
<p>Void Linux: <a href="https://github.com/void-linux/void-packages/tree/master/srcpkgs/i3blocks">i3blocks</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Or can be installed from source with:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>git clone https://github.com/vivien/i3blocks
cd i3blocks
./autogen.sh
./configure
make
make install</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_getting_started">Getting started</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In your i3 configuration file, define i3blocks as the <a href="https://i3wm.org/docs/userguide.html#status_command">status line command</a> of a new bar block:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>bar {
  status_command i3blocks
}</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The project&#8217;s repository does not include default scripts anymore.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>For the lazy, you can start from <a href="https://github.com/vivien/i3blocks-contrib">our collection of scripts</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>git clone https://github.com/vivien/i3blocks-contrib ~/.config/i3blocks
cd !$
cp config.example config</code></pre>
</div>
</div>
<div class="paragraph">
<p>For the picky, you can start a configuration file in one of the following preferred paths:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>$XDG_CONFIG_HOME/i3blocks/config</code> (or <code>~/.config/i3blocks/config</code>);</p>
</li>
<li>
<p><code>~/.i3blocks.conf</code>;</p>
</li>
<li>
<p><code>$XDG_CONFIG_DIRS/i3blocks/config</code> (or <code>/etc/xdg/i3blocks/config</code>);</p>
</li>
<li>
<p><code>/etc/i3blocks.conf</code>;</p>
</li>
<li>
<p>or any other path that you will specify using the <code>-c</code> option.</p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
By default <code>/etc</code> is prefixed by <code>/usr/local</code> when you installed from source.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Use the example above or dig in the configuration details below.</p>
</div>
<div class="paragraph">
<p>Now restart i3 with <code>i3-msg restart</code> to apply your changes.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_blocks">Blocks</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The configuration file uses a simplified INI file format:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini"># Properties not preceded by a section are considered global
# and merged into every section declarations.
foo=bar

[block1]
baz=qux

# This is a comment
[block2]
quux= quuz</code></pre>
</div>
</div>
<div class="paragraph">
<p>In this example, <em>block2</em> contains a <em>foo</em> property equal to <em>"bar"</em> and a <em>quux</em> property equal to <em>" quuz"</em> (including the leading space).
Everything after the equal sign will be part of the value, thus inline comments won&#8217;t be stripped out.</p>
</div>
<div class="paragraph">
<p>At runtime, these properties are simply variables, that are passed along to the status bar program when printing is necessary.
However on startup, i3blocks checks some optional properties to eventually setup the scheduling of a command.</p>
</div>
<div class="paragraph">
<p>If a block specifies a command, then all of its properties are passed as environment variables at execution, which means that the <em>foo=bar</em> property will be available from a shell script with <code>$foo</code>.
The output of the command is used to update the values of these variables.
The values are reset to default (as defined in the configuration file) before the update, so that blocks get a consistent behavior at each execution.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Each line from a block output must be terminated with a newline.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_i3bar_properties">i3bar properties</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In order to use i3blocks with i3, its status bar command <em>i3bar</em> expects specific keys.
To know how to customize the blocks of your status line, you must refer to the <a href="https://i3wm.org/docs/i3bar-protocol.html#_blocks_in_detail">i3bar protocol</a>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<em>full_text</em> is the only mandatory key, the block will be skipped if this key is absent or empty.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Unless overriden, the section name of the block defines the <em>name</em> key.</p>
</div>
<div class="paragraph">
<p>Below are examples of static blocks interacting with <em>i3bar</em>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[simple]
full_text=This is a looong white on red text
short_text=Short white on red text
background=#FF0000
color=#FFFFFF

# Block with a fixed width
[aligned]
full_text=Here.
min_width=100
align=center

# Fancy text with multiple colors and shapes
[funky]
full_text=&lt;span foreground="red" size="x-large"&gt;Roses&lt;/span&gt; and &lt;i&gt;&lt;span color="#EE37B8"&gt;violets&lt;/span&gt;&lt;/i&gt;!
markup=pango</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_i3blocks_properties">i3blocks properties</h2>
<div class="sectionbody">
<div class="paragraph">
<p>These are some special properties checked by i3blocks on startup.
These will be considered as simple variables at runtime.</p>
</div>
<div class="sect2">
<h3 id="_command">command</h3>
<div class="paragraph">
<p>The optional <em>command</em> property specifies a command line to be executed with <code>sh -c</code>.
The command can be relative to the configuration file where it is defined.
If the command outputs some text, it is used to update the block.</p>
</div>
<div class="paragraph">
<p>An exit code of 0 means success.
A special exit code of <em>33</em> will set the <em>urgent</em> i3bar key to true.
Any other exit code will raise an error.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[pacman]
full_text=c ·
command=echo "· ${full_text~~}"
color=#FFFF00</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_interval">interval</h3>
<div class="paragraph">
<p>The optional <em>interval</em> property specifies when the command must be scheduled.</p>
</div>
<div class="paragraph">
<p>A positive value represents the number of seconds to wait between exectutions.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini"># Print seconds since 1970-01-01
[epoch]
command=date +%s
interval=1</code></pre>
</div>
</div>
<div class="paragraph">
<p>A value of <em>0</em> (or undefined) means the command is not timed whatsoever and will not be executed on startup.
This is useful to trigger the command only on user input (e.g. signal or click), not before.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini"># Restart i3 on click
[restart]
full_text=Restart
command=i3-msg -q restart
#interval=0</code></pre>
</div>
</div>
<div class="paragraph">
<p>The interval value <em>once</em> (or <em>-1</em>) will schedule the command only on startup.
This tells i3blocks not to schedule the command again on a time basis.
But events such as signals and clicks will execute the command again of course.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini"># Fetch the public IP address only on startup
[public-ip]
command=wget -qO - icanhazip.com
interval=once</code></pre>
</div>
</div>
<div class="paragraph">
<p>The interval value <em>repeat</em> (or <em>-2</em>) will respawn the command as soon as it terminates.
This is convenient for blocking programs which exit as soon as the awaited event arises.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
clicks are not supported with this value, since such commands are unlikely to expect data on their standard input.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini"># Print the last command entered in Bash
[history]
command=inotifywait -qq -e close_write ~/.bash_history; tail -1 ~/.bash_history
interval=repeat</code></pre>
</div>
</div>
<div class="paragraph">
<p>The interval value <em>persist</em> (or <em>-3</em>) expects the command to be an infinite loop.
Each line of the output will trigger an update of the block.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[window]
command=xtitle -s
interval=persist</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_signal">signal</h3>
<div class="paragraph">
<p>Blocks can be scheduled upon reception of a real-time signal (think prioritized and queueable).
The range of available signal numbers is <em>1</em> to <em>N</em>, where <em>SIGRTMIN+N = SIGRTMAX</em>.
(Note: there are 31 real-time signals in Linux.)</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[caps-lock]
command=xset -q | grep Caps | awk '{ print $2, $3, $4 }'
interval=once
signal=10</code></pre>
</div>
</div>
<div class="paragraph">
<p>This example block above will be scheduled once i3blocks handles the <em>SIGRTMIN+10</em> signal.
This can be sent directly from an i3 binding on Caps Lock release with the following configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>bindsym --release Caps_Lock exec pkill -SIGRTMIN+10 i3blocks</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_format">format</h3>
<div class="paragraph">
<p>There are several formats supported to specify which variables i3blocks must update.
Some favor simplicity over flexibility but thus can be limited.</p>
</div>
<div class="paragraph">
<p>When undefined, a raw format is assumed.
Each line of the output corresponds to an i3bar key, in the order of definition found in the <a href="https://i3wm.org/docs/i3bar-protocol.html#_blocks_in_detail">i3bar protocol</a>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>the 1st line updates the <em>full_text</em>;</p>
</li>
<li>
<p>the 2nd line updates the <em>short_text</em>;</p>
</li>
<li>
<p>the 3rd line updates the <em>color</em>;</p>
</li>
<li>
<p>the 4th line updates the <em>background</em>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Excess lines are considered an error.
Below is an example of a simple battery script.</p>
</div>
<div class="listingblock">
<div class="title">battery.sh</div>
<div class="content">
<pre class="highlight"><code class="language-sh" data-lang="sh">#!/bin/bash

BAT=$(acpi -b | grep -E -o '[0-9][0-9]?%')

# Full and short texts
echo "Battery: $BAT"
echo "BAT: $BAT"

# Set urgent flag below 5% or use orange below 20%
[ ${BAT%?} -le 5 ] &amp;&amp; exit 33
[ ${BAT%?} -le 20 ] &amp;&amp; echo "#FF8000"

exit 0</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[battery]
command=battery.sh
interval=10</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <em>json</em> format can update any variable.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[counter]
_count=0
command=printf '{"full_text":"Counter: %s", "_count":%d}\n' $_count $((_count + 1))
format=json
interval=1</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_click">Click</h2>
<div class="sectionbody">
<div class="paragraph">
<p>When you click on a block, data such as the button number and coordinates are merged into the block variables.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<em>name</em> and <em>instance</em> are the two keys used by i3bar to identify a block.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The data sent on click is detailed in the <a href="https://i3wm.org/docs/i3bar-protocol.html#_click_events">i3bar protocol</a>.</p>
</div>
<div class="paragraph">
<p>If the block command isn&#8217;t already spawned, it is executed again.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini"># Print click data
[clickme]
align=center
full_text=Click me!
min_width=Button=? x=? y=?
command=echo "Button=$button x=$x y=$y"</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the value of the block&#8217;s interval is <em>persist</em>, then the data is written on the command standard input, one line per click.
What gets written depends on the block&#8217;s format.
The raw format only gets the click button.
The JSON format gets all block variables.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[click-loop]
full_text=Click me!
command=while read button; do echo "Got click $button"; done
interval=persist

[click-loop-json]
full_text=Click me!
command=ruby -r json -n -e '$_ = JSON.parse($_)' -e '$_["full_text"] = "Click %s at (%d,%d)" % $_.slice("button", "x", "y").values' -e 'puts JSON.dump($_)' -e 'STDOUT.flush'
interval=persist
format=json</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_faq">FAQ</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Frequently Asked Questions and Troubleshooting.</p>
</div>
<div class="qlist qanda">
<ol>
<li>
<p><em>What is a blocklet?</em></p>
<p>A blocklet is the configuration of a single block, part of the status line.
There are plenty listed in the <a href="https://vivien.github.io/i3blocks/blocklets">blocklets page</a>.</p>
</li>
<li>
<p><em>Can I use my own variables?</em></p>
<p>Yes, any variable defined in the block is exported as is to the environment of its command.
The <code>foo=bar</code> property can be accessed with <code>$foo</code> from a shell script, <code>ENV["foo"]</code> from Ruby, and so on.</p>
<div class="paragraph">
<p>The IEEE and The Open Group state that <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html">"The name space of environment variable names containing lowercase letters is reserved for applications."</a>.
i3bar suggests to prefix your own keys with an underscore (<code>_</code>), but it might be more intuitive to use uppercase environment variables, so it is your call to define your own naming convention.</p>
</div>
</li>
<li>
<p><em>Why <code>$foo</code> doesn&#8217;t work from the configuration file?</em></p>
<p>i3blocks does not do string interpolation of any sort.
The definitions found in the configuration file are just raw strings, this means that <code>bar=$baz</code> defines a <em>bar</em> variable equal to literally <code>$baz</code> (a dollar sign followed by "baz").</p>
<div class="paragraph">
<p>String interpolation does work in the <em>command</em> property though, since it is interpreted by a shell which has access to the environment variables.</p>
</div>
</li>
<li>
<p><em>How can I simulate a button?</em></p>
<p>This is pretty straightforward actually.
Just make sure not to override the <em>full_text</em>, for example:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[calc-button]
full_text=Calculator
command=gnome-calculator &gt;/dev/null</code></pre>
</div>
</div>
</li>
<li>
<p><em>Can a block start a GUI application?</em></p>
<p>Sure.
And if you do not wish your command to block until the application is closed, ask i3 to start it for you with <code>i3-msg -q exec myapp</code>.</p>
</li>
<li>
<p><em>Why Pango isn&#8217;t working?</em></p>
<p>The Pango markup requires a Pango font.
Make sure you configured <a href="https://i3wm.org/docs/userguide.html#_font">i3bar</a> to use a Pango font.
For example:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>font pango:Inconsolata, Icons 12</code></pre>
</div>
</div>
</li>
<li>
<p><em>Why is <code>printf</code> not working?</em></p>
<p>As of i3blocks 1.5, each line from a block output are expected to be terminated with a newline, e.g. with <code>printf "&#8230;&#8203;\n"</code> from a shell script.</p>
</li>
<li>
<p><em>Why is the output from my persistent block not displayed?</em></p>
<p>Make sure to flush stdout, for example:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[ruby-loop]
full_text=Click me
command=ruby -p -e '$_.prepend("Got button ")' -e 'STDOUT.flush'
interval=persist</code></pre>
</div>
</div>
</li>
<li>
<p><em>Can I use a time interval below 1 second?</em></p>
<p>No, the time unit for interval is the second.</p>
<div class="paragraph">
<p>But even though I wouldn&#8217;t recommend it, you can still update faster than that with loops:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[nano1]
command=sleep .5; date +%N
interval=repeat

[nano2]
command=while sleep .5; do date +%N; done
interval=persist</code></pre>
</div>
</div>
</li>
<li>
<p><em>Can I change the block separator?</em></p>
<p>Not with i3blocks itself, separators are drawn by i3bar.
You can change the <em>separator_symbol</em> in the <a href="https://i3wm.org/docs/userguide.html#_custom_separator_symbol">i3bar configuration</a>.</p>
<div class="paragraph">
<p>Alternatively, you can define static blocks as custom separators in your i3blocks configuration.
In the example below, we use the <em>"\xe3\x80\x89"</em> UTF-8 character:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini"># Define the custom separator in global properties for boilerplate
full_text=〉
align=center
color=#666666
separator=false
separator_block_width=7

[time]
instance=la
TZ=America/Los_Angeles
command=date +%T
interval=5

[separator]

[time]
instance=nc
TZ=Pacific/Noumea
command=date +%T
interval=5

[separator]

[time]
instance=mtl
TZ=America/Montreal
command=date +%T
interval=5</code></pre>
</div>
</div>
</li>
</ol>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_debugging">Debugging</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The log level can be increased with the <code>-v</code> option.</p>
</div>
<div class="paragraph">
<p>If your window manager (and thus this program) is run via systemd, you can inspect the program outputs with <code>journalctl -t &lt;identifier&gt; -f</code>.
You may also use this in conjonction with running the program manually with <code>systemd-cat -t &lt;identifier&gt; ./i3blocks</code>.</p>
</div>
<div class="paragraph">
<p>Alternatively you can redirect the standard output and error streams from the program invokation with:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>bar {
  status_command 2&gt;/tmp/i3blocks.err /path/to/i3blocks -vvv -c /path/to/config | tee /tmp/i3blocks.out
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>And inspect the log with <code>tail -f /tmp/i3blocks.err</code>.</p>
</div>
<div class="paragraph">
<p>See the <a href="i3blocks.1.html">manpage</a> for details about the command line options and i3blocks usage.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_license">License</h2>
<div class="sectionbody">
<div class="paragraph">
<p>i3blocks is Copyright &#169; Vivien Didelot</p>
</div>
<div class="paragraph">
<p>See the file COPYING for information of licensing and distribution.</p>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
</div>
</div>
</body>
</html>